home *** CD-ROM | disk | FTP | other *** search
/ EnigmA Amiga Run 1995 October / EnigmA AMIGA RUN 01 (1995)(G.R. Edizioni)(IT)[!][issue 1995-10][Aminet 7].iso / Aminet / gfx / show / flick_1_5.lha / src / flxspec.txt < prev    next >
Text File  |  1993-03-28  |  38KB  |  972 lines

  1. Animator Pro File Formats
  2.  
  3.  
  4. This chapter details each of the file formats defined by Animator
  5. Pro.  Formats supported by Animator Pro but defined by another
  6. party, such as GIF and TIFF files, are not described in this
  7. document.
  8.  
  9. The files created by Autodesk Animator Pro are a superset of
  10. those created by the original Autodesk Animator.  In some cases
  11. the Animator Pro formats are identical with the older Animator
  12. format.  In other cases, new data fields or data compression
  13. techniques have been added to the file.
  14.  
  15. All two-byte and four-byte data values in Animator Pro files are
  16. stored in Intel-style order, the same as they would appear in
  17. memory on an 80x86 machine.
  18.  
  19.  
  20. Common Hierarchial Chunked File Structure
  21.  
  22.  
  23. In general, Animator Pro files contain one or more chunks of
  24. information.  Conceptually, a chunk is a combination of control
  25. information and data.  The most common Animator Pro file format
  26. is a header structure followed by hierarchial data chunks.
  27.  
  28. Every chunk begins with a header of at least 6 bytes. The first
  29. four bytes contain the length of the chunk (including the header
  30. itself, and also including the length of all subordinate chunks,
  31. if any).  The next two bytes are an identifier word which
  32. describes the type of data in the chunk.  Some chunks have
  33. headers longer than six bytes, but the size and identifier fields
  34. always occupy the first six bytes of the header.
  35.  
  36. The Animator Pro animation file is a good example of a hierarchial
  37. chunked file structure.  The data in an animation file is arranged 
  38. as follows:
  39.  
  40.      animation file:
  41.           optional prefix chunk:
  42.                settings chunk
  43.                cel placement chunk
  44.           frame 1 chunk:
  45.                postage stamp chunk:
  46.                     postage stamp data
  47.                color palette chunk
  48.                pixel data chunk
  49.           frame 2 chunk:
  50.                pixel data chunk
  51.           frame 3 chunk:
  52.                color palette chunk
  53.                pixel data chunk
  54.           frame 4 chunk:
  55.                color palette chunk
  56.           ring frame chunk:
  57.                color palette chunk
  58.                pixel data chunk
  59.  
  60. It is possible that new types of chunks not described in this
  61. document will be added to animation files in the future.  We
  62. recommend that you quietly ignore unknown chunk types you
  63. encounter during animation playback.  The size fields in the
  64. chunk headers make it easy to skip an entire unrecognized chunk.
  65.  
  66.  
  67. FLC - Animator Pro Flic Files
  68.  
  69.  
  70. This is the main animation file format created by Animator Pro.
  71. The file contains a 128-byte header, followed by an optional
  72. prefix chunk, followed by one or more frame chunks.
  73.  
  74. The prefix chunk, if present, contains Animator Pro settings
  75. information, CEL placement information, and other auxiliary data.
  76.  
  77. A frame chunk exists for each frame in the animation. In
  78. addition, a ring frame follows all the animation frames.  Each
  79. frame chunk contains color palette information and/or pixel data.
  80.  
  81. The ring frame contains delta-compressed information to loop from
  82. the last frame of the flic back to the first.  It can be helpful
  83. to think of the ring frame as a copy of the first frame,
  84. compressed in a different way.  All flic files will contain a
  85. ring frame, including a single-frame flic.
  86.  
  87.  
  88. The FLC file header
  89.  
  90.  
  91. A FLC file begins with a 128-byte header, described below.  All
  92. lengths and offsets are in bytes.  All values stored in the
  93. header fields are unsigned.
  94.  
  95. Offset  Length  Name         Description
  96.  
  97.   0       4     size         The size of the entire animation file,
  98.                              including this file header.
  99.  
  100.   4       2     magic        File format identifier. Always hex AF12.
  101.  
  102.   6       2     frames       Number of frames in the flic.  This 
  103.                              count does not include the ring frame.  
  104.                              FLC files have a maximum length of 4000 
  105.                              frames.
  106.  
  107.   8       2     width        Screen width in pixels.
  108.  
  109.   10      2     height       Screen height in pixels.
  110.  
  111.   12      2     depth        Bits per pixel (always 8).
  112.  
  113.   14      2     flags        Set to hex 0003 after ring frame is 
  114.                              written and flic header is updated.  
  115.                              This indicates that the file was properly
  116.                              finished and closed.
  117.  
  118.   16      4     speed        Number of milliseconds to delay between 
  119.                              each frame during playback.
  120.  
  121.   20      2     reserved     Unused word, set to 0.
  122.  
  123.   22      4     created      The MSDOS-formatted date and time of the
  124.                              file's creation.
  125.  
  126.   26      4     creator      The serial number of the Animator Pro
  127.                              program used to create the file.  If the 
  128.                              file was created by some other program 
  129.                              using the FlicLib development kit, this 
  130.                              value is hex 464C4942 ("FLIB").
  131.  
  132.   30      4     updated      The MSDOS-formatted date and time of the
  133.                              file's most recent update.
  134.  
  135.   34      4     updater      Indicates who last updated the file.  See 
  136.                              the description of creator.
  137.  
  138.   38      2     aspectx      The x-axis aspect ratio at which the file 
  139.                              was created.
  140.  
  141.   40      2     aspecty      The y-axis aspect ratio at which the file 
  142.                              was created. Most often, the x:y aspect ratio 
  143.                              will be 1:1.  A 320x200 flic has a ratio of 
  144.                              6:5.
  145.  
  146.   42      38    reserved     Unused space, set to zeroes.
  147.  
  148.   80      4     oframe1      Offset from the beginning of the file to the 
  149.                              first animation frame chunk.
  150.  
  151.   84      4     oframe2      Offset from the beginning of the file to
  152.                              the second animation frame chunk.  This value 
  153.                              is used when looping from the ring frame back 
  154.                              to the second frame during playback.
  155.  
  156.   88      40    reserved     Unused space, set to zeroes.
  157.  
  158.  
  159.  
  160. The FLC prefix chunk
  161.  
  162.  
  163. An optional prefix chunk may immediately follow the animation
  164. file header.  This chunk is used to store auxiliary data which is
  165. not directly involved in the animation playback.  The prefix
  166. chunk starts with a 16-byte header (identical in structure to a
  167. frame header), as follows:
  168.  
  169. Offset  Length  Name         Description
  170.  
  171.   0       4     size         The size of the prefix chunk, including 
  172.                              this header and all subordinate chunks 
  173.                              that follow.
  174.  
  175.   4       2     type         Prefix chunk identifier. Always hex F100.
  176.  
  177.   6       2     chunks       Number of subordinate chunks in the
  178.                              prefix chunk.
  179.  
  180.   8       8     reserved     Unused space, set to zeroes.
  181.  
  182. To determine whether a prefix chunk is present, read the 16-byte
  183. header following the file header.  If the type value is hex F100,
  184. it's a prefix chunk.  If the value is hex F1FA it's the first
  185. frame chunk, and no prefix chunk exists.
  186.  
  187. Note
  188.  
  189. Programs other than Animator Pro should never need to create flic
  190. files that contain a prefix chunk.  Programs reading a flic file
  191. should skip the prefix chunk by using the size value in the prefix 
  192. header to read and discard the prefix, or by seeking directly to 
  193. the first frame using the oframe1 field from the file header.
  194.  
  195.  
  196. The FLC frame chunks
  197.  
  198.  
  199. Frame chunks contain the pixel and color data for the animation.
  200. A frame chunk may contain multiple subordinate chunks, each
  201. containing a different type of data for the current frame.  Each
  202. frame chunk starts with a 16-byte header that describes the contents 
  203. of the frame:
  204.  
  205. Offset  Length  Name         Description
  206.  
  207.   0       4     size         The size of the frame chunk, including this
  208.                              header and all subordinate chunks that follow.
  209.  
  210.   4       2     type         Frame chunk identifier. Always hex F1FA.
  211.  
  212.   6       2     chunks       Number of subordinate chunks in the
  213.                              frame chunk.
  214.  
  215.   8       8     reserved     Unused space, set to zeroes.
  216.  
  217.  
  218. Immediately following the frame header are the frame's subordinate 
  219. data chunks.  When the chunks count in the frame header is zero, it 
  220. indicates that this frame is identical to the previous frame.  This 
  221. implies that no change is made to the screen or color palette, but
  222. the appropriate delay is still inserted during playback.
  223.  
  224. Each data chunk within a frame chunk is formatted as follows:
  225.  
  226. Offset  Length  Name         Description
  227.  
  228.   0       4     size         The size of the chunk, including this header.
  229.  
  230.   4       2     type         Data type identifier.
  231.  
  232.   6    (size-6) data         The color or pixel data.
  233.  
  234.  
  235. The type values in the chunk headers indicate what type of graphics 
  236. data the chunk contains and which compression method was used to 
  237. encode the data.  The following values (and their associated mnemonic 
  238. names) are currently found in frame data chunks:
  239.  
  240. Value     Name        Description
  241.  
  242.   4    FLI_COLOR256   256-level color palette info
  243.   7    FLI_SS2        Word-oriented delta compression
  244.   11   FLI_COLOR      64-level color palette info
  245.   12   FLI_LC         Byte-oriented delta compression
  246.   13   FLI_BLACK      Entire frame is color index 0
  247.   15   FLI_BRUN       Byte run length compression
  248.   16   FLI_COPY       No compression
  249.   18   FLI_PSTAMP     Postage stamp sized image
  250.  
  251. The following sections describe each of these data encoding methods 
  252. in detail.
  253.  
  254.  
  255. Chunk Type  4 (FLI_COLOR256) - 256-Level Color
  256.  
  257.  
  258. The data in this chunk is organized in packets.  The first word
  259. following the chunk header is a count of the number of packets in
  260. the chunk.  Each packet consists of a one-byte color index skip
  261. count, a one-byte color count and three bytes of color information 
  262. for each color defined.
  263.  
  264. At the start of the chunk, the color index is assumed to be zero.
  265. Before processing any colors in a packet, the color index skip
  266. count is added to the current color index.  The number of colors
  267. defined in the packet is retrieved.  A zero in this byte indicates 
  268. 256 colors follow.  The three bytes for each color define the red, 
  269. green, and blue components of the color in that order. Each 
  270. component can range from 0 (off) to 255 (full on).  The data to 
  271. change colors 2,7,8, and 9 would appear as follows:
  272.  
  273.      2                      ; two packets
  274.      2,1,r,g,b              ; skip 2, change 1
  275.      4,3,r,g,b,r,g,b,r,g,b  ; skip 4, change 3
  276.  
  277.  
  278. Chunk Type 11 (FLI_COLOR) - 64-Level Color
  279.  
  280. This chunk is identical to FLI_COLOR256 except that the values 
  281. for the red, green and blue components are in the range of 0-63
  282. instead of 0-255.
  283.  
  284.  
  285. Chunk Type 13 (FLI_BLACK) - No Data
  286.  
  287. This chunk has no data following the header.  All pixels in the
  288. frame are set to color index 0.
  289.  
  290.  
  291. Chunk Type 16 (FLI_COPY) - No Compression
  292.  
  293. This chunk contains an uncompressed image of the frame. The 
  294. number of pixels following the chunk header is exactly the width
  295. of the animation times the height of the animation.  The data
  296. starts in the upper left corner with pixels copied from left to
  297. right and then top to bottom.  This type of chunk is created when
  298. the preferred compression method (SS2 or BRUN) generates more
  299. data than the uncompressed frame image; a relatively rare 
  300. situation.
  301.  
  302.  
  303. Chunk Type 15 (FLI_BRUN) - Byte Run Length Compression
  304.  
  305. This chunk contains the entire image in a compressed format.
  306. Usually this chunk is used in the first frame of an animation, or
  307. within a postage stamp image chunk.
  308.  
  309. The data is organized in lines.  Each line contains packets of
  310. compressed pixels.  The first line is at the top of the animation, 
  311. followed by subsequent lines moving downward.  The number of lines 
  312. in this chunk is given by the height of the animation.
  313.  
  314. The first byte of each line is a count of packets in the line.
  315. This value is ignored, it is a holdover from the original Animator.  
  316. It is possible to generate more than 255 packets on a line.  The 
  317. width of the animation is now used to drive the decoding of packets 
  318. on a line; continue reading and processing packets until width 
  319. pixels have been processed, then proceed to the next line.
  320.  
  321. Each packet consist of a type/size byte, followed by one or more
  322. pixels.  If the packet type is negative it is a count of pixels
  323. to be copied from the packet to the animation image.  If the packet 
  324. type is positive it contains a single pixel which is to be 
  325. replicated; the absolute value of the packet type is the number
  326. of times the pixel is to be replicated.
  327.  
  328.  
  329. Chunk Type 12 (FLI_LC) - Byte Aligned Delta Compression
  330.  
  331. This chunk contains the differences between the previous frame
  332. and this frame.  This compression method was used by the original
  333. Animator, but is not created by Animator Pro.  This type of chunk
  334. can appear in an Animator Pro file, however, if the file was
  335. originally created by Animator, then some (but not all) frames
  336. were modified using Animator Pro.
  337.  
  338. The first 16-bit word following the chunk header contains the
  339. position of the first line in the chunk. This is a count of lines
  340. (down from the top of the image) which are unchanged from the
  341. prior frame.  The second 16-bit word contains the number of lines
  342. in the chunk.  The data for the lines follows these two words.
  343.  
  344. Each line begins with two bytes.  The first byte contains the
  345. starting x position of the data on the line, and the second byte
  346. the number of packets for the line.  Unlike BRUN compression, the
  347. packet count is significant (because this compression method is
  348. only used on 320x200 flics).
  349.  
  350. Each packet consists of a single byte column skip, followed by a
  351. packet type/size byte.  If the packet type is positive it is a
  352. count of pixels to be copied from the packet to the animation
  353. image.  If the packet type is negative it contains a single pixel
  354. which is to be replicated; the absolute value of the packet type
  355. gives the number of times the pixel is to be replicated.
  356.  
  357. Note
  358.  
  359. The negative/positive meaning of the packet type bytes in LC
  360. compression is reversed from that used in BRUN compression.  This
  361. gives better performance during playback.
  362.  
  363.  
  364. Chunk Type  7 (FLI_SS2) - Word Aligned Delta Compression
  365.  
  366. This format contains the differences between consecutive frames.
  367. This is the format most often used by Animator Pro for frames
  368. other than the first frame of an animation.  It is similar to the
  369. line coded delta (LC) compression, but is word oriented instead
  370. of byte oriented.  The data is organized into lines and each line
  371. is organized into packets.
  372.  
  373. The first word in the data following the chunk header contains
  374. the number of lines in the chunk.  Each line can begin with some
  375. optional words that are used to skip lines and set the last byte
  376. in the line for animations with odd widths.  These optional words
  377. are followed by a count of the packets in the line.  The line
  378. count does not include skipped lines.
  379.  
  380.  
  381. The high order two bits of the word is used to determine the
  382. contents of the word.
  383.  
  384.      Bit 15  Bit 14       Meaning
  385.  
  386.        0      0           The word contains the packet count.  The
  387.                           packets follow this word.  The packet count 
  388.                           can be zero; this occurs when only the last 
  389.                           pixel on a line changes.
  390.  
  391.        1      0           The low order byte is to be stored in the 
  392.                           last byte of the current line.  The packet 
  393.                           count always follows this word.
  394.  
  395.        1      1           The word contains a line skip count.  The 
  396.                           number of lines skipped is given by the 
  397.                           absolute value of the word.  This word can 
  398.                           be followed by more skip counts, by a last 
  399.                           byte word, or by the packet count.
  400.  
  401. The packets in each line are similar to the packets for the line
  402. coded chunk.  The first byte of each packet is a column skip count.  
  403. The second byte is a packet type. If the packet type is positive, 
  404. the packet type is a count of words to be copied from the packet to 
  405. the animation image.  If the packet type is negative, the packet 
  406. contains one more word which is to be replicated. The absolute value
  407. of the packet type gives the number of times the word is to be 
  408. replicated.  The high and low order byte in the replicated word do 
  409. not necessarily have the same value.
  410.  
  411.  
  412. Chunk Type 18 (FLI_PSTAMP) - Postage Stamp Image
  413.  
  414. This chunk type holds a postage stamp -- a reduced-size image --
  415. of the frame.  It generally appears only in the first frame chunk
  416. within a flic file.
  417.  
  418. When creating a postage stamp, Animator Pro considers the ideal
  419. size to be 100x63 pixels.  The actual size will vary as needed to
  420. maintain the same aspect ratio as the original.
  421.  
  422. The pixels in a postage stamp image are mapped into a six-cube
  423. color space, regardless of the color palette settings for the
  424. full frame image.  A six-cube color space is formed as follows:
  425.  
  426.      start at palette entry 0
  427.      for red = 0 thru 5
  428.           for green = 0 thru 5
  429.                for blue = 0 thru 5
  430.                     palette_red   = (red   * 256)/6
  431.                     palette_green = (green * 256)/6
  432.                     palette_blue  = (blue  * 256)/6
  433.                     move to next palette entry
  434.                end for blue
  435.           end for green
  436.      end for red
  437.  
  438. Any arbitrary rgb value (where each component is in the range of
  439. 0-255) can be mapped into the six-cube space using the formula:
  440.  
  441.   ((6*red)/256)*36 + ((6*green)/256)*6 + ((6*blue)/256)
  442.  
  443. When a frame data chunk has been identified as a postage stamp,
  444. the header for the chunk contains more fields than just size and
  445. type.  The full postage stamp chunk header is defined as follows:
  446.  
  447. Offset  Length  Name         Description
  448.  
  449.   0       4     size         The size of the postage stamp chunk,
  450.                              including this header.
  451.  
  452.   4       2     type         Postage stamp identifier; always 18.
  453.  
  454.   6       2     height       Height of the postage stamp image, in
  455.                              pixels.
  456.  
  457.   8       2     width        Width of the postage stamp image, in
  458.                              pixels.
  459.  
  460.   10      2     xlate        Color translation type; always 1,
  461.                              indicating six-cube color space.
  462.  
  463. Immediately following this header is the postage stamp data.  The
  464. data is formatted as a chunk with standard size/type header.  The
  465. type will be one of:
  466.  
  467.      Value    Name           Description
  468.  
  469.      15     FPS_BRUN         Byte run length compression
  470.      16     FPS_COPY         No compression
  471.      18     FPS_XLAT256      Six-cube color xlate table
  472.  
  473. The FPS_BRUN and FPS_COPY types are identical to the FLI_BRUN and
  474. FLI_COPY encoding methods described above.
  475.  
  476. The FPS_XLAT256 type indicates that the chunk contains a 256-byte
  477. color translation table instead of pixel data.  To process this
  478. type of postage stamp, read the pixel data for the full-sized 
  479. frame image, and translate its pixels into six-cube space using a 
  480. lookup in the 256-byte color translation table.  This type of
  481. postage stamp appears when the size of the animation frames is 
  482. smaller than the standard 100x63 postage stamp size.
  483.  
  484.  
  485. FLI - Original Animator Flic Files
  486.  
  487.  
  488. This animation file format is limited to 320x200 resolution.  It
  489. is the main animation file format of the original Animator, and
  490. is still used by Animator Pro for creating 320x200 animations.
  491. The file structure is very similar to that of a FLC file.  A FLI
  492. file does not contain a prefix chunk, and does not use FLI_PSTAMP
  493. or FLI_SS2 data encoding in the frame chunks.
  494.  
  495.  
  496. The FLI file header
  497.  
  498.  
  499. The file header for a FLI file is a subset of the FLC file
  500. header.  It is defined as follows:
  501.  
  502. Offset  Length  Name         Description
  503.  
  504.   0       4     size         The size of the entire animation file,
  505.                              including this file header.
  506.  
  507.   4       2     magic        File format identifier. Always hex AF11.
  508.  
  509.   6       2     frames       Number of frames in the flic. This count
  510.                              does not include the ring frame.  FLI files 
  511.                              have a maximum length of 4000 frames.
  512.  
  513.   8       2     width        Screen width in pixels. This is always
  514.                              320 in a FLI file.
  515.  
  516.   10      2     height       Screen height in pixels. This is always
  517.                              200 in a FLI file.
  518.  
  519.   12      2     depth        Bits per pixel (always 8).
  520.  
  521.   14      2     flags        Always zero in a FLI file.
  522.  
  523.   16      2     speed        Number of jiffies to delay between each
  524.                              frame during playback.  A jiffy is 1/70 
  525.                              of a second.
  526.  
  527.   18      110   reserved     Unused space, set to zeroes.
  528.  
  529.  
  530. The FLI frame chunks
  531.  
  532.  
  533. One or more frame chunks immediately follow the FLI file header.
  534. The frame chunks in a FLI file are identical to those in a FLC
  535. file, except that postage stamp image (FLI_PSTAMP) and
  536. word-runlength-compression (FLI_SS2) data chunks never appear in
  537. FLI files.
  538.  
  539.  
  540. CEL - Animation Cel Files
  541.  
  542.  
  543. CEL files contain one or more frames of image data. Both Animator
  544. Pro and the original Animator produce CEL files, but each uses a
  545. different file format.
  546.  
  547. To process a CEL file for input, read the first 2 bytes of the
  548. file.  If they are hex 9119, the file is an original Animator CEL
  549. file.  If the first two bytes are not 9119, it is an Animator Pro
  550. CEL file.
  551.  
  552.  
  553. Animator Pro CEL Files
  554.  
  555.  
  556. An Animator Pro CEL file is identical to a FLC file in all
  557. respects.  A CEL file should have a Celdata chunk in the file
  558. prefix chunk which describes the x,y placement of the CEL.  If
  559. the Celdata placement chunk is not present, assume a placement of
  560. 0,0.
  561.  
  562.  
  563. Original Animator CEL Files
  564.  
  565.  
  566. The original Animator also produced CEL files.  These were
  567. still-picture files, not the multi-frame files Animator Pro now
  568. uses.  A CEL file from the original Animator is identical to a
  569. PIC file from the original Animator in all respects.
  570.  
  571.  
  572. PIC - Picture Files
  573.  
  574.  
  575. PIC files contain still images in an uncompressed format.  Both
  576. the original Animator and Animator Pro produce PIC files.  The
  577. file formats are different; Animator Pro produces a hierarchial
  578. chunked file, while the original Animator file is a simpler fixed
  579. format. These formats are detailed in the following sections.
  580.  
  581. To process a PIC file for input, read the first 2 bytes of the
  582. file.  If they are hex 9119, the file is an original Animator PIC
  583. format file.  If the first two bytes are not 9119, it is an
  584. Animator Pro PIC file.
  585.  
  586.  
  587. Animator Pro PIC Files
  588.  
  589.  
  590. Animator Pro uses this format to store a single-frame picture
  591. image or bitmap.  This format description applies to both PIC and
  592. MSK files.  The file begins with a 64-byte header defined as
  593. follows:
  594.  
  595. Offset  Length  Name         Description
  596.  
  597.   0       4     size         The size of the file, including this header.
  598.  
  599.   4       2     magic        File format identifier. Always hex 9500.
  600.  
  601.   6       2     width        The width of the image, in pixels.
  602.  
  603.   8       2     height       The height of the image, in pixels.
  604.  
  605.   10      2     xcoord       The X coordinate; typically zero.  (See
  606.                              note below).
  607.  
  608.   12      2     ycoord       The Y coordinate; typically zero.  (See
  609.                              note below).
  610.  
  611.   14      4     userid       An arbitrary 4-byte value; generally
  612.                              zero.  Do not count on any particular 
  613.                              value in this field.  Set this field to 
  614.                              zero when creating a file.
  615.  
  616.   18      1     depth        The number of bits per pixel. This is 8
  617.                              for PIC files and 1 for MSK files.
  618.  
  619.   19      45    reserved     Unused space; set to zeroes.
  620.  
  621.  
  622. Note
  623.  
  624. The xcoord and ycoord values in a PIC file header will typically
  625. be zero.  Non-zero values indicate that the file contains a
  626. rectangle from within a larger picture.  In this case, the xcoord
  627. and ycoord values represent the relation of the saved rectangle
  628. to the full image.  These values can be safely ignored for most
  629. purposes.
  630.  
  631. Following the file header are the data chunks for the image.
  632. Each data chunk within a PIC or MSK file is formatted as follows:
  633.  
  634. Offset  Length  Name         Description
  635.  
  636.   0       4     size         The size of the chunk, including this header.
  637.  
  638.   4       2     type         Data type identifier.
  639.  
  640.   6    (size-6) data         The color or pixel data.
  641.  
  642. The type values in the chunk headers indicate what type of 
  643. graphics data the chunk contains.  The following values (and 
  644. their associated mnemonic names) are currently found in PIC/MSK 
  645. data chunks:
  646.  
  647.      Value    Name            Description
  648.  
  649.      0    PIC_CMAP            Color palette info
  650.      1    PIC_BYTEPIXELS      Byte-per-pixel image data
  651.      2    PIC_BITPIXELS       Bit-per-pixel mask data
  652.  
  653. In a PIC_CMAP chunk, the first 2-byte word is a version code; 
  654. currently this is set to zero.  Following the version word are
  655. all 256 palette entries in rgbrgb... order.  Each of the r, g,
  656. and b components is a single byte in the range of 0-255.  This
  657. type of chunk appears in PIC files; there will generally be no
  658. color map chunk in a MSK file.
  659.  
  660. In a PIC_BYTEPIXELS chunk, the image data appears immediately
  661. following the 6-byte chunk header.  The data is stored as one
  662. byte per pixel, in left-to-right, topD to-bottom sequence.  This
  663. type of chunk appears in PIC files.
  664.  
  665. In a PIC_BITPIXELS chunk, the bitmap data appears immediately
  666. following the 6-byte chunk header.  The data is stored as bits
  667. packed into bytes such that the leftmost bits appear in the
  668. high-order positions of each byte.  The bits are stored in
  669. left-to-right, top-toD bottom sequence.  When the width of the
  670. bitmap is not a multiple of 8, there will be unused bits in the
  671. lowD order positions of the last byte on each line.  The number
  672. of bytes per line is ((width+7)/8).  This type of chunk appears
  673. in MSK files.
  674.  
  675.  
  676. Original Animator PIC Files
  677.  
  678.  
  679. The original Animator uses this format to store a single-frame
  680. picture image.  This format description applies to both PIC and
  681. CEL files.  The file begins with a 32 byte header, as follows:
  682.  
  683. Offset  Length  Name         Description
  684.  
  685.   0       2     type         File type identifier.  Always hex 9119.
  686.  
  687.   2       2     width        Width of image.  Always 320 in a PIC
  688.                              file; may be any value in a CEL file.
  689.  
  690.   4       2     height       Height of image.  Always 200 in a PIC
  691.                              file; may be any value in a CEL file.
  692.  
  693.   6       2     xcoord       X coordinate for upper left corner of
  694.                              the image.  Always zero in a PIC file; 
  695.                              may be non-zero in a CEL file.
  696.  
  697.   8       2     ycoord       Y coordinate for upper left corner of
  698.                              the image.  Always zero in a PIC file; 
  699.                              may be non-zero in a CEL file.
  700.  
  701.   10      1     depth        Number of bits per pixel; always 8.
  702.  
  703.   11      1     compress     Compression flag; always zero.
  704.  
  705.   12      4     datasize     Size of the image data in bytes.
  706.  
  707.   16      16    reserved     Unused space; set to zeroes.
  708.  
  709. Immediately following the header is the color map.  It contains
  710. all 256 palette entries in rgbrgb... order. Each of the r, g, and
  711. b components is a single byte in the range of 0-63.  Following
  712. the color palette is the image data, one byte per pixel.  The
  713. image data is stored in left-to-right, top-to-bottom sequence.
  714.  
  715.  
  716. MSK - Mask Data Files
  717.  
  718.  
  719. MSK files contain a bitmap image.  Both Animator Pro and the
  720. original Animator produce MSK files, but the formats are
  721. different.
  722.  
  723. To process a MSK file for input, check the file size. If it is
  724. exactly 8000 bytes, the file is an original Animator MSK file.
  725. If the file is any other size, it is an Animator Pro MSK file.
  726.  
  727.  
  728. Animator Pro MSK Files
  729.  
  730.  
  731. An Animator Pro MSK file is identical to an Animator Pro PIC
  732. file.  It will have a pixel depth of 1.
  733.  
  734.  
  735. Original Animator MSK Files
  736.  
  737.  
  738. A MSK file created by the original Animator is exactly 8000 bytes
  739. long.  There is no file header or other control information in
  740. the file.  It contains the image bit map, 1 bit per pixel, with
  741. the leftmost pixels packed into the high order bits of each byte.
  742. The size of the image is fixed at 320x200.  The image is stored
  743. left-to-right, top-to-bottom.
  744.  
  745.  
  746. COL - Color Map Files
  747.  
  748.  
  749. A COL file stores the rgb values for entries in the color palette.  
  750. Both Animator Pro and the original Animator produce COL files, but 
  751. the formats are different.
  752.  
  753. To process a COL file for input, check the file size. If it is
  754. exactly 768 bytes, the file is an original Animator COL file.  If
  755. the file is any other size, it is an Animator Pro COL file.
  756.  
  757.  
  758. Animator Pro COL Files
  759.  
  760.  
  761. An Animator Pro COL file stores color palette information.  The
  762. file begins with an 8-byte header defined as follows:
  763.  
  764. Offset  Length  Name         Description
  765.  
  766.   0       4     size         The size of the file, including this header.
  767.  
  768.   4       2     magic        File format identifier. Always hex B123.
  769.  
  770.   6       2     version      The version of color storage format.
  771.                              Currently set to zero, indicating 
  772.                              256-level color data in each r,g,b 
  773.                              component.
  774.  
  775. Following the file header are palette entries in rgbrgb... order.
  776. Each of the r, g, and b components is a single byte in the range
  777. of 0-255.  Generally, there will be data for 256 palette entries,
  778. but this cannot be assumed.  The actual number of palette entries
  779. is ((size-8)/3); if this value is not an even multiple of three,
  780. the file is corrupted.
  781.  
  782.  
  783. Original Animator COL Files2
  784.  
  785.  
  786. A COL file created by the original Animator is exactly 768 bytes
  787. long.  There is no file header or other control information in
  788. the file.  The rgb values for all 256 palette entries is stored
  789. in rgbrgb... sequence. Each of the r, g, and b values is in the
  790. range of 0-63.
  791.  
  792.  
  793. PLY - Polygon Files
  794.  
  795.  
  796. A PLY file holds a set of points that describe a polygon.  Both
  797. Animator Pro and the original Animator create PLY files.  The
  798. file format is the same for both.
  799.  
  800. A PLY file starts with an 8-byte header, as follows:
  801.  
  802. Offset  Length  Name         Description
  803.  
  804.   0       2     points       Count of points in the file.
  805.  
  806.   2       4     reserved     Unused space; set to zero.
  807.  
  808.   6       1     closed       Closed-shape flag.  If 1, there is an
  809.                              implied connection between the last point 
  810.                              and the first.  If zero, the shape is not 
  811.                              closed.
  812.  
  813.   7       1     magic        File format identifier. Always hex 99.
  814.  
  815. The points data follows the file header.  Each point is described
  816. with three 16-bit integers, representing the x, y, and z
  817. coordinates of each point.  The z coordinates are always zero.
  818.  
  819.  
  820. TWE - Tween Data Files
  821.  
  822. A TWE file holds information about a tweening operation set up
  823. via the Tween menus.  The information includes the starting and
  824. ending shapes, and the optional userD specified links between the
  825. shapes.  Animator Pro creates tween files.
  826.  
  827. A TWE file begins with an 8-byte header defined as follows:
  828.  
  829. Offset  Length  Name         Description
  830.  
  831.   0       2     magic        File format identifier. Always hex 1995.
  832.  
  833.   2       2     version      The file format version; always zero.
  834.  
  835.   4       4     tcount       The number of tween shapes in the file;
  836.                              always 2.
  837.  
  838.   8       8     reserved     Unused space; set to zeroes.
  839.  
  840.   16      4     linkcount    The number of link entries in the file.
  841.  
  842. Immediately following the file header are the link entries.  If
  843. the linkcount value is zero there are no links.  Each link entry
  844. is a pair of 32-bit integers. The first value in each pair is the
  845. index of the point in the first shape, and the second value is
  846. the index of the point in the ending shape.  (IE, a link value of
  847. 2,7 says to link the second starting-shape point to the seventh
  848. ending-shape point.)
  849.  
  850. Following the link entries is the data block that describes the
  851. starting shape, then the data block that describes the ending
  852. shape.  The format of these blocks is identical to that of the
  853. polygon (PLY) file, including file header data.  In other words,
  854. they appear as if a pair of polygon files are embedded in the
  855. tween file at this point.
  856.  
  857.  
  858. OPT - Optics Menu Settings Files
  859.  
  860.  
  861. An OPT file holds information about an optics operation set up
  862. via the Optics menus.  Both Animator Pro and the original
  863. Animator create OPT files.  The file format is the same for both.
  864.  
  865. An OPT file starts with a 4-byte header, as follows:
  866.  
  867. Offset  Length  Name         Description
  868.  
  869.   0       2     magic        File type identifier.  Always hex 1A3F.
  870.  
  871.   2       2     count        Number of records in the file.
  872.  
  873. Following the file header are optics records of 50 bytes each.  A
  874. record is generated for each click on CONTINUE MOVE in the OPTICS
  875. menu.  The move records are formatted as follows:
  876.  
  877. Offset  Length  Name         Description
  878.  
  879.   0       4     link         In the file, this field is always zero.
  880.                              In memory, it's a pointer to the next 
  881.                              move record.
  882.  
  883.   4       6     spincenter   The x,y,z coordinates of the spin
  884.                              center point; three 16-bit values.
  885.  
  886.   10      6     spinaxis     The x,y,z coordinates of the spin axis;
  887.                              three 16-bit values.
  888.  
  889.   16      6     spinturns    The x,y,z coordinates of the spin turns;
  890.                              three 16-bit values.
  891.  
  892.   22      4     spininter    Intermediate turns.  Two 16-bit values.
  893.                              These are values for a conjugation matrix 
  894.                              that corresponds to spin axis.
  895.  
  896.   26      6     sizecenter   The x,y,z coordinates of the size
  897.                              center point; three 16-bit values.
  898.  
  899.   32      2     xmultiplier  Determines (along with xdivisor)
  900.                              how to scale along x dimension.
  901.  
  902.   34      2     xdivisor     Determines (along with xmultiplier) how
  903.                              to scale along x dimension.
  904.  
  905.   36      2     ymultiplier  Determines (along with ydivisor)
  906.                              how to scale along y dimension.
  907.  
  908.   38      2     ydivisor     Determines (along with ymultiplier) how
  909.                              to scale along y dimension.
  910.  
  911.   40      2     bothmult     Like xmultiplier, but applied to both
  912.                              dimensions.
  913.  
  914.   42      2     bothdiv      Like xdivisor, but applied to both
  915.                              dimensions.
  916.  
  917.   44      6     linearmove   The x,y,z offset for a linear move;
  918.                              three 16-bit values.
  919.  
  920.  
  921. Internal Usage Files (REC, SET, CFG, GLV, MU)
  922.  
  923.  
  924. Each of these file types is created by Animator Pro to store
  925. internal data between sessions.  These files must not be touched
  926. by other applications.
  927.  
  928. REC files store macros.  Animator Pro REC files are not the same
  929. as the REC files documented with the original Animator.
  930.  
  931. SET files store internal settings information; they are created
  932. by the Quit|Save menu, and by the Save Default Settings menu.
  933.  
  934. CFG files store internal configuration information, such as the
  935. video driver and mode.
  936.  
  937. GLV files store Poco Global Variables.  The data is stored as a
  938. series of nullterminated strings, and must not be modified using
  939. a normal text editor.
  940.  
  941. MU files store menu text, prompts, error messages, etc,
  942. customized to the proper native language.  The data is stored as
  943. normal ASCII text, and must not be modified in any way.
  944.  
  945. End of document.  Below are a few comments that hold text we may
  946. want to suck back into the document some day.
  947. When the prefix chunk is present, it contains a fixed header
  948. structure, followed by one or more prefix sub-chunks.  The prefix
  949. chunk header is defined as follows:
  950.  
  951. The following constants identify the sub-chunks within a prefix
  952. chunk.
  953.  
  954.      enum {
  955.           FP_FREE        = 0,
  956.           FP_FLIPATH          = 1,
  957.           FP_VSETTINGS   = 2,
  958.           FP_CELDATA          = 3,
  959.           };
  960.  
  961.  
  962. Format for the optional Prefix chunk:
  963.  
  964. The prefix chunk at present contains:
  965. A settings chunk.  This is the same thing as a settings file but
  966. as a chunk in a flic.  This is how the load settings from a flic
  967. is implemented. This is present in flics but not cels. A settings
  968. chunk has sub chunks for things like the paths in the file
  969. requestors, optics settings, etc.
  970.  
  971. A Celdata chunk.  This chunk has the positioning info for a fli
  972. used as a cel.  This is usually only present in cel files.